1. Image API URI Syntax

The IIIF Image API can be called in two ways:

Request an image, which may be part of a larger image.
Request information about the image, including characteristics, functionality available, and related services.

Both convey the request's information in the path segments of the URI, rather than as query parameters.

There are four parameters shared by the requests, and other IIIF specifications:

Name	Description
scheme	Indicates the use of the HTTP or HTTPS protocol in calling the service.
server	The host server on which the service resides. The parameter may also include a port number.
prefix	The path on the host server to the service. This prefix is optional, but may be useful when the host server supports multiple services. The prefix MAY contain multiple path segments, delimited by slashes, but all other special characters MUST be encoded. See [URI Encoding and Decoding][uri-encoding-and-decoding] for more information.
identifier	The identifier of the requested image. This may be an ark, URN, filename, or other identifier. Special characters MUST be URI encoded.

The combination of these parameters forms the image’s base URI and identifies the underlying image content. It is constructed according to the following URI Template ([RFC6570][rfc-6570]):

{scheme}://{server}{/prefix}/{identifier}

1.1. Image Request URI Syntax

The IIIF Image API URI for requesting an image MUST conform to the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

For example:

http://www.example.org/image-service/abcd1234/full/full/0/default.jpg

The parameters of the Image Request URI include region, size, rotation, quality and format, which define the characteristics of the returned image. These are described in detail in [Image Request Parameters][image-request-parameters].

1.2. Image Information Request URI Syntax

The URI for requesting image information MUST conform to the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/info.json

For example:

http://www.example.org/image-service/abcd1234/info.json

National Library of Norway Example:

https://www.nb.no/services/image/resolver/URN:NBN:no-nb_digifoto_20141030_00064_NB_WF_TVK_042510/info.json

Returns:

{
    "@context": "http://iiif.io/api/image/2/context.json",
    "@id": "https://www.nb.no/services/image/resolver/URN:NBN:no-nb_digifoto_20141030_00064_NB_WF_TVK_042510",
    "protocol": "http://iiif.io/api/image",
    "sizes": [{
            "width": 3442,
            "height": 2890
        },
        {
            "width": 1721,
            "height": 1445
        },
        {
            "width": 860,
            "height": 722
        },
        {
            "width": 430,
            "height": 361
        },
        {
            "width": 215,
            "height": 180
        }
    ],
    "tiles": [{
        "width": 1024,
        "scaleFactors": [
            1,
            2,
            4,
            8,
            16,
            32
        ]
    }],
    "profile": [
        "http://iiif.io/api/image/2/level0.json",
        {
            "formats": [
                "jpg",
                "tif",
                "jp2"
            ],
            "supports": [
                "cors",
                "jsonldMediaType",
                "profileLinkHeader",
                "regionByPct",
                "regionByPx",
                "rotationBy90s",
                "sizeByWhListed",
                "sizeByForcedWh",
                "sizeByH",
                "sizeByPct",
                "sizeByW",
                "sizeByWh"
            ]
        }
    ],
    "width": 6884,
    "height": 5780
}

This tell us that this image is 5780 pixels wide, and 6884 pixels high.

It also provides the viewing software with additional information about what content the image server can provide.

In this case, we know that this is a level 0 image server. But also, that the server can return jpg, tif or jp2 formatted files, that it supports rotation in 90 degree increments, and so on.

The compliance levels are described here: https://iiif.io/api/image/2.1/compliance/

This image can be seen in context at:

https://www.nb.no/items/161a7690c31f0512859a4aeaeaa8476f?page=0&searchText=

2. Image API Paramters

All parameters described below are required for compliant construction of a IIIF Image API URI. The sequence of parameters in the URI MUST be in the order described below. The order of the parameters is also intended as a mnemonic for the order of the operations by which the service should manipulate the image content.

2.1. Region

The region parameter defines the rectangular portion of the full image to be returned. Region can be specified by pixel coordinates, percentage or by the value "full", which specifies that the entire image should be returned.

Form	Description
`full`	The complete image is returned, without any cropping.
`square`	The region is defined as an area where the width and height are both equal to the length of the shorter dimension of the complete image. The region may be positioned anywhere in the longer dimension of the image content at the server's discretion, and centered is often a reasonable default.
x,y,w,h	The region of the full image to be returned is specified in terms of absolute pixel values. The value of x represents the number of pixels from the 0 position on the horizontal axis. The value of y represents the number of pixels from the 0 position on the vertical axis. Thus the x,y position 0,0 is the upper left-most pixel of the image. w represents the width of the region and h represents the height of the region in pixels.
pct:x,y,w,h	The region to be returned is specified as a sequence of percentages of the full image's dimensions, as reported in the image information document. Thus, `x` represents the number of pixels from the 0 position on the horizontal axis, calculated as a percentage of the reported width. `w` represents the width of the region, also calculated as a percentage of the reported width. The same applies to y and h respectively. These may be floating point numbers.

4.2. Size

The size parameter determines the dimensions to which the extracted region is to be scaled.

Form	Description
`full`	The image or region is not scaled, and is returned at its full size. Note [deprecation warning][full-dep].
`max`	The image or region is returned at the maximum size available, as indicated by `maxWidth`, `maxHeight`, `maxArea` in the [profile description][profile-description]. This is the same as `full` if none of these properties are provided.
w,	The image or region should be scaled so that its width is exactly equal to w, and the height will be a calculated value that maintains the aspect ratio of the extracted region.
,h	The image or region should be scaled so that its height is exactly equal to h, and the width will be a calculated value that maintains the aspect ratio of the extracted region.
pct:n	The width and height of the returned image is scaled to n% of the width and height of the extracted region. The aspect ratio of the returned image is the same as that of the extracted region.
w,h	The width and height of the returned image are exactly w and h. The aspect ratio of the returned image MAY be different than the extracted region, resulting in a distorted image.
!w,h	The image content is scaled for the best fit such that the resulting width and height are less than or equal to the requested width and height. The exact scaling MAY be determined by the service provider, based on characteristics including image quality and system performance. The dimensions of the returned image content are calculated to maintain the aspect ratio of the extracted region.

4.3. Rotation

The rotation parameter specifies mirroring and rotation. A leading exclamation mark ("!") indicates that the image should be mirrored by reflection on the vertical axis before any rotation is applied. The numerical value represents the number of degrees of clockwise rotation, and may be any floating point number from 0 to 360.

Form	Description
n	The degrees of clockwise rotation from 0 up to 360.
!n	The image should be mirrored and then rotated as above.

4.4. Quality

The quality parameter determines whether the image is delivered in color, grayscale or black and white.

Quality	Parameter Returned
`color`	The image is returned in full color.
`gray`	The image is returned in grayscale, where each pixel is black, white or any shade of gray in between.
`bitonal`	The image returned is bitonal, where each pixel is either black or white.
`default`	The image is returned using the server's default quality (e.g. color, gray or bitonal) for the image.

4.5. Format

The format of the returned image is expressed as an extension at the end of the URI.

Extension	MIME Type
`jpg`	image/jpeg
`tif`	image/tiff
`png`	image/png
`gif`	image/gif
`jp2`	image/jp2
`pdf`	application/pdf
`webp`	image/webp

It is probably a good idea to check the info.json for supported formats, or default to jpg, as many servers will not support all of these formats.